Shareware Grab Bag/Shareware Grab Bag.iso/007/basappl9.arc/TIMECALC.DOC

Text File | 1987-07-18 | 13.9 KB | 315 lines

                    DOCUMENTATION FOR TIMECALC.BAS

            Copyright 1983 Ny Michael Csontos
                      3228 Livonia Center Road
                      Lima, New York 14485


        INTRODUCTION

    This program was written as a means of gaining experience working
with the IBM Color/Graphics Adapter display buffer in the alphanumeric mode.
Therefor the Color/Graphics Adapter must be present for it to run.

    The program is a calculator for time units in which each entry and
result appears at fixed screen locations. Data is entered and read directly
to and from the screen buffer thus making data handling similar to that in a
pocket calculator. All calculations are made in double precision to accomodate
the range of a millisecond to a century.

        PROGRAM OPERATION

    THE DESCRIPTION SCREEN

    When the program is run you will first be presented with a screen
of general information. It will tell you, among other things, that you can
program the function keys in BASIC in the direct mode before running the
program. You may then press <Esc> to return to BASIC to do this or any other
key to continue.

    <Esc> will end the program any time an input is requested. Since you
may use the printer for some functions, the end routine tries to reset the
printer for compressed print. If there is no printer present, the program
will just end. However if the printer is present but off-line, you will get
the DOS printer time-out delay before the BASIC prompt appears on the screen.

    If you return to BASIC to program a function key, the procedure is
as follows: Without a line number, just type

        KEY n, "d...d"       <Enter>

where n is the number of the function key and d...d is the number you want
to enter on the screen whenever you press the key. If you do not program the
keys they will retain whatever functions they had for the BASIC editor.

    If you use this program often and want to skip the introductory screen,
list lines 10300 and 15300. They should be:

10300 'GOTO 11600'------------------temporary skip description screen------

            and

15300 'GOTO 15900'------------------temporary skip to data screen----------

If they are not, the program has been renumbered by someone and the GOTO's are
wrong. You would have to find new line numbers for the GOTO's. If the lines
are correct, just delete the first of the two "'"'s in each one to go straight
to the data screen from RUN.

    THE DATA SCREEN

    The upper part of the data screen provides fields to enter time,
function, or a constant for multiplication or division. You address a field
by moving the "<" symbol with the cursor control keys. Numbers are entered
from the right-hand end of the field as on most calculators. The backspace
and delete keys remove characters one at a time. The exception to this is the
function line, where the function is selected by pressing the space bar.

    In order to allow the use of the numeric keypad for number entry, the
cursor functions are duplicated with the function keys. <Alt>+<F7> is cursor
left, <Alt>+<F8> is cursor right, <Alt>+<F6> is cursor up, <Alt>+<F10> is
cursor down, and <Alt>+<F9> is Delete. Of course <shift> plus the numeric
keypad key in numeric mode will also give the cursor function.

    The entries are not limited to the number of digits indicated by the
size of the fields on the initial data screen. Up to ten characters may be
entered into any field. The field will expand to the appropriate size.
Entries may be any decimal number of ten characters or less. 1234567890 or
12345.6789 or .000012345 are ok in any field. Double precision calculations
carry about 15 decimal digits, however the last three are subject to round-
off error. Use caution in interpreting the results if you mix years and
milliseconds in the same calculation.

    To start a calculation, press <enter>. The information visible on the
screen is read and processed and the result is presented in the result section
of the screen.

    RESULTS

    Processed data is presented in several ways. First in fields  similar
to the entry format. Then as whole numbers of weeks, dys, hours, or minutes
with the rest of the units broken down. Finally as decimal fractions of years,
weeks, days, hours, minutes, or seconds.

    All of the data is rounded to single precision except the seconds
displayed in the lower right-hand corner. This is left double precision
to be compared with the seconds listed in the lower right-hand corner. Any
difference in the two indicates that round-off error has been significant. The
results should be accurate to within two decimal places of where the two
seconds results differ.

    The calculations are made by performing the function selected on each
unit individually, then converting all of the units to seconds, then
recalculating all of the units from the resulting seconds. This minimises
the round-off error which would result from sobtacting seconds from years.

    If no function has been selected and there is data on the first entry
line, the program breaks down the entry into units as when the breakdown
function is selected. If you try to make a subtraction that would result in
a negative time you are prompted to use a function key that reverses the
entries.

    LENGTH OF YEAR

    This program assumes a 365 day year. It is not possible t
consistantly take leap years into account since a time span of three days
may include a February 29 while another of 4 years, 11.9 months may not. Thus
when you are entering times involving years, keep the 365 day year in  ind
and add the appropriate number of days in needed.

    An exception to this is the date calculation (see <Ctrl>+<F7> below).
This function will automaticly insert an extra day for every four years in
the YEARS units of the result. It also will take February 29ths into account
when incrementing the date by days and weeks.  If you are using the date
calculation as more than an estimate, then do some careful checking of the
result of <Ctrl>+<F7> or <Ctrl>+<F8>.

    THE FUNCTION KEYS

    As mentioned above you may program the straight <F1> to <F10> keys
to enter constants. However most of the <Alt>, <shift>, and <Ctrl> function
key functions are also used by this program.

        <Alt>+<F1>  LIST KEYS

    This key will scroll through all of the function key functions on
line 25 of the screen. A prompt to use this key is displayed on line 25 after
each calculation. Since the message for this key is the same as the prompt
it may appear that nothing happens until second press of <F1>.

        <Alt>+<F2> CLEAR FIELD

    The field at the "<" location is erased. This may be faster than
holding down the <Del> or backspace keys. It has no effect on the function
selection field.

        <Alt>+<F3> RESULT TO INPUT 1

    The results of the last calculation as they appear on the second line
of the result section of the screen will be transfered to the first of the
entry lines of the screen. They may then be used for additional calculations.

        <Alt>+<F4> CLEAR LINE

    Erases the entire contents of the line containing the "<" pointer.
This clears it for the entry of new data. It does not clear the function line.

        <Alt>+<F5> RESULT TO INPUT 3

      The same as <Alt>+<F3> above except that the result goes to the last
data entry line.  This transfer is made even if the line is invisible because
multiply, divide, or breakdown have been selected. The transfered data will
be available when "+" or "-" are selected.

        <Alt>+<F6> through <Alt>+<F10> CURSOR CONTROL

    These allow the use of the numeric keypad for data entry. See the
Data Screen section above.

        <shift>+<F1> AND <shift>+<F2> SAVE DATA 1

    These keys allow you to keep the entire first data line in memory for
repeated use. <shift>+<F1> stores the data and <shift>+<F2> retreives it.

        <shift>+<F3> and <shift>+<F4> SAVE CONSTANT

    Same as for <shift>+<F1> and <shift>+<F2> above but for the constant
used for multiplication or division. This function operates even if the line
is invisible because you have selected "*", "/", or breakdown.

        <shift>+<F5> and <shift>+<F6> SAVE DATA 3

    These store and retreive respectively the data on the last time data
entry line. They also work even if the line is not displayed. All save
functions use different memory locations so may be used independantly.

        <shift>+<F7> and <Shift>+<F8> SAVE RESULT

    The result line is stored and retreived respectively by these keys.
The result may then be transfered to either of the entry fields for further
calculations.

        <shift>+<F9> PRINT CALCULATION REPORT

    The printer will print a dump of all of the double precision results
of the last calculation. This may be useful to interpret rounding errors or
to make full use of the precision available.  The numbers are in the form
0.nnnnnnnnnnnnnnnD±ee. The decimal point must be moved the number of places
and in the direction indicated by the sign ("±") to the right of the D.

    The first section of the report lists the input as entered and the
result. The second section lists individual units of years to seconds as
decimal fractions. Each number is the total value of the result. The third
section lists the largest whole units of the result for each of the units.
This is like an INT function for time units.

    An EPSON MX-80 printer is assumed and its control characters are used.
If no printer is present this function will be inactive. If a printer is
present but off line, there will be a delay equal to the DOS printer error
time-out before the program will continue. An error message will be flashed
briefly on screen line 25.


        <shift>+<F10> PRINTER LOG

    This key is a toggle function; i.e., the first time it is pressed
it turns the function on, the next time it turns it off. When on, it makes
the printer print a line for each calculation listing the input data and
result in a compact form in compressed print. It can substitute for a pencil
and notebook.

    If there is no printer it will flash an error message, but if the
printer is off-line, there will be the time-out delay.

        <Ctrl>+<F1> EXCHANGE INPUT

    There are several times when it is necessary to exchange the input
data, as when subtraction would produce negative time or when this program
is used as a timer. <Ctrl>+<F1> acomplishes this.

        <Ctrl>+<F2> PRINT FUNCTION KEY TABLE

    The printer will print a list of all of the function key functions
on an 8½" x 11" page. The list barely fits so align the paper carefully.
Double spacing was used to allow for notes and underlining.

        <Ctrl>+<F3> and <Ctrl>+<F4> ENTER CURRENT TIME

    This function will read the BASIC [TIME$] function and enter the hours,
minutes, and seconds data from it on the first and the last time input data
lines respectively. Of course this only will be correct if TIME in DOS was
initialized when the computer was turned on or the direct command:

        TIME$="hh:mm:ss"

was entered before this program was run.

    The program keeps updating the time until <enter> is pressed. If a
function is selected that requires time to execute, the display will not be
updated until the function ends but then will be current. The resolution of
the time information is slightly less than one second since the updating
routine takes about 3/4 second to execute.

    This time entry function allows the program to be used as a stopwatch.
Set the function for subtraction. Press <Ctrl>+<F4> to display the current
time on the last data line. Start timing by pressing <Ctrl>+<F3>. End timing
by pressing <enter>. The elapsed time (±1 sec.) will be displayed in the
result section.

        <Ctrl>+<F5> and <Ctrl>+<F6> ENTER DATE

    These keys use the BASIC [DATE$] function to enter the number of days
from the start of the year to the current date into the days data field of the
first and last data lines respectively. This may be useful if the program
is used for scheduling or planning purposes.

    Of course the DATE function in DOS must have been initialized for
the date entered to be correct.

        <Ctrl>+<F7> and <Ctrl>+<F8> CONVERT RESULT TO DATE

    These functions add the result to the start of the current year or to
the current date and calculate a new date from this.  The date is displayed
on the last line of the result part of the screen display.  The DOS [DATE]
must be properly set for this calculation to be correct.

    The date calculation attempts to take leap years into account. Weeks
and days in the result are converted into days and the BASIC [DATE$] function
is used to increment the date the required number of days. The number of
years is added to the year of the date and the number of leap-years in that
time span is added to the days count.  Nevertheless since time span
calculations (based on 365 day years) may not have been consistant with
this method, dates should be considered estimates only.

        <Ctrl>+<F9> and <Ctrl>+<F10> are unassigned



        MISCELLANEOUS

    This program uses a considerable amount of memory for storing strings
of characters. Although it was developed on a 64k system, if you use all of
the special functions, especially the save functions, you may run out of
string space in a 64K memory especially if you use additions to DOS like the
key redefinition program "FK". If this happens, either load a minimal version
of DOS or use the function keys sparingly.

    No specific application was planned for this program. Timing record
selections, calculating timings for tape recordings, planning production
schedules, or figuring out how many minutes till you retire are some
suggestions. The author does not guarantee the accuracy of the results. In
writing this program he came to appreciate why Dr. Who has so much trouble
landing when he expects to.



                     ---***---


    The program TIMECALC.BAS and the file TIMECALC.DOC are
    made freely available for non-exclusive distribution
    to members of the Picture City Personal Computer
    Programing Club and through software exchange with
    other users' groups as long as the author and (PC)^3
    are fully credited.